Skip to content

[wip] Add optimisticKey docs#8326

Draft
rickhanlonii wants to merge 1 commit intoreactjs:mainfrom
rickhanlonii:rh/optimistic-key-docs
Draft

[wip] Add optimisticKey docs#8326
rickhanlonii wants to merge 1 commit intoreactjs:mainfrom
rickhanlonii:rh/optimistic-key-docs

Conversation

@rickhanlonii
Copy link
Member

WIP - this is only the claude output, which is pretty good but I need to review / verify it.

@github-actions
Copy link

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page Size (compressed) First Load
/[[...markdownPath]] 128.84 KB (🟡 +13 B) 243.93 KB
Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this.


return (
<div>
<button onClick={() => handleAddTodo('New todo')}>
Copy link

@MaxwellCohen MaxwellCohen Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to have a button to add a todo without using the optimisticKey, so it is easier to see the benefit of this api.


<Experimental>

**This API is experimental and is not available in a stable version of React yet.**

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What feedback does the React team want regarding optimisticKey (and other experimental APIs)?

Some APIs are mostly complete and just need testing for the next release, or for web standards to reach the point where they can be used (like ). Then there are some APIs that edge cases and additional use cases might need to be figured out about (like fragment references).

For optimisticKey it seems like this is an API that needs to be tested before being released in React 19.3 or 20

@samselikoff
Copy link
Contributor

Awesome first pass! Two thoughts:

  1. Animation is always an area where changing keys have bit me in the past, so might be great to include it as a usage example. For example if you have a list of messages (think iMessage) and you animate the new message from Composer up to the list, you give it a key. When the persisted message comes back it should match the optimistic key, otherwise you might get funky behavior when animating. It's a nice use case that's not necessarily about internal state, but more about the identity that key represents. (I'm more familiar with the problem when using libs like Motion but I imagine we could show a similar example with ViewTransitions, where you'd expect an update view transition to smoothly translate the message up, but because in the optimisticKey-less version you swap keys, you actually end up triggering an exit/enter instead.)
  2. You should only be able to assign optimisticKey if you're in a transition, right? Do we error if you don't? If so maybe we can highlight this under caveats or troubleshooting.


<Note>

Compare this to the [`useOptimistic`](/reference/react/useOptimistic#optimistically-adding-to-a-list) example, which uses `crypto.randomUUID()` as the key. That approach works for showing optimistic items, but loses component state when the real item replaces it. Use `optimisticKey` when your list items have internal state you want to preserve.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should update the useOptimistic example to mention the experimental API and then only use optimisticKey once it lands in Canary.

Even now, I'd prefer if we have the comparison side-by-side like suggested in https://github.com/reactjs/react.dev/pull/8326/changes#r2866143024

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants